Skip to content

feat(gh-aw): add scheduled and evidence-triggered retrospectives - #2005

Merged
tamirdresher merged 5 commits into
github:devfrom
tamirdresher:tamirdresher-microsoft-squad-retrospective-workflow
Sep 8, 2026
Merged

tamirdresher merged 5 commits into
github:devfrom
tamirdresher:tamirdresher-microsoft-squad-retrospective-workflow

Conversation

@tamirdresher

Copy link
Copy Markdown
Collaborator

Adds scheduled and manual retrospectives, evidence-triggered early requests, durable pending-request recovery, deduplication and cooldown safeguards, and review-gated corrective actions.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@github-actions

github-actions Bot commented Sep 7, 2026

Copy link
Copy Markdown
Contributor

⚠️ Squad File Leakage Detected

The following .squad/ files were modified in this PR:

  • .squad/skills/gh-aw-enlistment/SKILL.md

These files affect team routing, agent charters, and decisions.
If intentional, ensure approval from the team lead.

@github-actions

github-actions Bot commented Sep 7, 2026 •

Copy link
Copy Markdown
Contributor

🟠 Impact Analysis — PR #2005

Risk tier: 🟠 HIGH

📊 Summary

Metric Count
Files changed 28
Files added 9
Files modified 19
Files deleted 0
Modules touched 8

🎯 Risk Factors

  • 28 files changed (21-50 → HIGH)
  • 8 modules touched (5-8 → HIGH)

📦 Modules Affected

ci-workflows (2 files)
  • .github/agents.md
  • .github/workflows/squad-ci.yml
docs (1 file)
  • docs/src/content/docs/guide/gh-aw.md
root (13 files)
  • .changeset/squad-retro-auto-implement.md
  • .changeset/squad-retrospective-workflow.md
  • README.md
  • workflows/shared/builtins/ralph-charter.md
  • workflows/shared/squad-improvement-gate.mjs
  • workflows/shared/squad-retro-evidence.mjs
  • workflows/shared/squad-retro-provenance.mjs
  • workflows/shared/squad.md
  • workflows/squad-implement-worker.md
  • workflows/squad-improvement-worker.md
  • workflows/squad-retro.md
  • workflows/squad-review.md
  • workflows/squad.md
scripts (1 file)
  • scripts/check-workflow-input-interpolation.mjs
squad-cli (1 file)
  • packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md
squad-sdk (1 file)
  • packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md
squad-state (1 file)
  • .squad/skills/gh-aw-enlistment/SKILL.md
tests (8 files)
  • test/gh-aw-command-parse.test.ts
  • test/gh-aw-enlistment-skill.test.ts
  • test/gh-aw-implement-workflow.test.ts
  • test/gh-aw-improvement-worker.test.ts
  • test/gh-aw-quality.test.ts
  • test/gh-aw-retro-workflow.test.ts
  • test/gh-aw-review-workflow.test.ts
  • test/gh-aw-security-scan.test.ts

This report is generated automatically for every PR. See #733 for details.

@github-actions

github-actions Bot commented Sep 7, 2026 •

Copy link
Copy Markdown
Contributor

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit db1558c

PR Scope: 🔧 Infrastructure

⚠️ 3 item(s) to address before review

Status Check Details
❌ Single commit 5 commits — consider squashing before review
✅ Not in draft Ready for review
✅ Branch up to date Up to date with dev
❌ Copilot review No Copilot review yet — it may still be processing
✅ Changeset present Changeset file found
✅ Scope clean ⚠️ PR includes 1 .squad/ file(s) — ensure these are intentional
✅ No merge conflicts No merge conflicts
✅ Copilot threads resolved All 1 Copilot thread(s) resolved
❌ CI passing 9 check(s) still running

Files Changed (28 files, +9451 −285)

File +/−
.changeset/squad-retro-auto-implement.md +20 −0
.changeset/squad-retrospective-workflow.md +7 −0
.github/agents.md +17 −4
.github/workflows/squad-ci.yml +11 −6
.squad/skills/gh-aw-enlistment/SKILL.md +34 −11
README.md +32 −1
docs/src/content/docs/guide/gh-aw.md +185 −15
packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md +34 −11
packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md +34 −11
scripts/check-workflow-input-interpolation.mjs +21 −10
test/gh-aw-command-parse.test.ts +62 −0
test/gh-aw-enlistment-skill.test.ts +5 −2
test/gh-aw-implement-workflow.test.ts +654 −13
test/gh-aw-improvement-worker.test.ts +521 −0
test/gh-aw-quality.test.ts +50 −0
test/gh-aw-retro-workflow.test.ts +3749 −0
test/gh-aw-review-workflow.test.ts +32 −15
test/gh-aw-security-scan.test.ts +11 −12
workflows/shared/builtins/ralph-charter.md +11 −0
workflows/shared/squad-improvement-gate.mjs +420 −0
workflows/shared/squad-retro-evidence.mjs +1526 −0
workflows/shared/squad-retro-provenance.mjs +743 −0
workflows/shared/squad.md +22 −70
workflows/squad-implement-worker.md +194 −3
workflows/squad-improvement-worker.md +181 −0
workflows/squad-retro.md +707 −0
workflows/squad-review.md +25 −2
workflows/squad.md +143 −99

Total: +9451 −285


This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@github-actions

github-actions Bot commented Sep 7, 2026 •

Copy link
Copy Markdown
Contributor

🏗️ Architectural Review

⚠️ Architectural review: 1 warning(s).

Severity Category Finding Files
🟡 warning sweeping-refactor This PR touches 28 files (28 modified/added, 0 deleted). Large PRs are harder to review — consider splitting if possible. —

Automated architectural review — informational only.

@tamirdresher

Copy link
Copy Markdown
Collaborator Author

Pushed CI repairs in 4633a875 while keeping this PR draft.

  • Dispatch-schema validation is now receiver-aware: issue-scoped workers retain issue_number; squad-retro requires retro_reason + request_origin, with a negative mutation test against the shipped relay.
  • Aligned the displayed Retro Relay mode with squad-retro-relay and trimmed only the new relay prose so the existing 191 KB guard passes unchanged.
  • Added the required CLI/SDK patch changeset.
  • Approved scope is explicitly 22 files: the original 19 plus the validator, its existing quality suite, and the changeset.

Validation: 410 tests passed in one sequential affected-suite run; input-interpolation gate passed; package build passed; all five workflows strict-compiled; final read-only review approved.

@tamirdresher
tamirdresher marked this pull request as ready for review September 8, 2026 14:23
Copilot AI lite review requested due to automatic review settings September 8, 2026 14:23

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟡 Changes recommended

workflows/squad-retro.md uses non-cron schedule strings (not valid GitHub Actions cron), which will prevent the workflow from loading/triggering correctly.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review tier: Lite
Findings: 1 High severity

New issues introduced by this change (1)
Severity Finding
High severity workflows/​squad-retro.md — The schedule.cron values here are not valid GitHub Actions cron expressions (they must be 5-field…
What changed in this PR

Adds a new Squad retrospective workflow (squad-retro) and wires it into the existing gh-aw entrypoints (router, reviewer, implement worker), plus updates docs, templates, CI gates, and tests so the new workflow is included in the shipped surface.

Changes:

  • Introduces workflows/squad-retro.md and its deterministic evidence gate (workflows/shared/squad-retro-evidence.mjs) to drive scheduled/manual/evidence-triggered retrospectives with cooldown/dedup/pending recovery.
  • Allows bounded retrospective “wakeup” dispatches from squad-review (on REQUEST_CHANGES) and squad-implement-worker (on persistent failures), and adds a /squad retro relay mode.
  • Updates installer docs/templates, CI strict-compile checks, and test suites to include the 5-workflow install/compile surface and validate the new gate logic.
File Description
workflows/​squad.md Adds squad-retro to dispatch allowlist and documents /squad retro relay skill.
workflows/​squad-review.md Permits a single bounded dispatch-workflow to squad-retro only on REQUEST_CHANGES.
workflows/​squad-retro.md New retrospective workflow with schedule/dispatch inputs, deterministic pre-agent gate, and bounded safe outputs.
workflows/​squad-implement-worker.md Allows squad-retro dispatch and documents early-evidence wakeup behavior.
workflows/​shared/​squad.md Updates shared bootstrap install surface to include squad-retro.
workflows/​shared/​squad-retro-evidence.mjs New deterministic evidence collection + eligibility evaluation logic for retros.
workflows/​shared/​builtins/​ralph-charter.md Adds instructions for Ralph to request a retro evidence wakeup.
scripts/​check-workflow-input-interpolation.mjs Generalizes dispatch payload validation to support non-issue-scoped receivers like squad-retro.
test/​gh-aw-security-scan.test.ts Updates entrypoint enumeration to include squad-retro.
test/​gh-aw-review-workflow.test.ts Updates reviewer contract expectations to allow only squad-retro dispatch.
test/​gh-aw-retro-workflow.test.ts Adds comprehensive unit + integration coverage for retro gate/workflow wiring.
test/​gh-aw-quality.test.ts Adds quality gate coverage for retro dispatch schemas and shipped relay validation.
test/​gh-aw-implement-workflow.test.ts Updates implement workflow tests for new dispatch allowlist and budget invariants.
test/​gh-aw-enlistment-skill.test.ts Updates enlistment skill expectations to include 5 workflows / 10 generated files.
README.md Updates install instructions and documents /squad retro.
packages/​squad-sdk/​templates/​skills/​gh-aw-enlistment/​SKILL.md Updates SDK template docs to include the new workflow in bootstrap steps.
packages/​squad-cli/​templates/​skills/​gh-aw-enlistment/​SKILL.md Updates CLI template docs to include the new workflow in bootstrap steps.
docs/​src/​content/​docs/​guide/​gh-aw.md Updates guide install/compile steps and adds retrospective lifecycle documentation.
.squad/​skills/​gh-aw-enlistment/​SKILL.md Updates canonical skill doc for 5-workflow install/compile surface.
.github/​workflows/​squad-ci.yml Expands strict-compile gate to compile/verify 5 workflows + 5 lockfiles.
.github/​agents.md Updates install instructions to include squad-retro.
.changeset/​squad-retrospective-workflow.md Ships the new workflow and template updates via CLI/SDK patch bumps.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread workflows/squad-retro.md Resolved

@bradygaster bradygaster left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Booster — CI/CD Review of PR #2005

Verdict: APPROVE

Deep-reviewed the full diff against dev (22 files), the compiled workflow surface, permissions, triggers, concurrency, and dedup/cooldown/pending-request-recovery logic in squad-retro-evidence.mjs.

What I verified directly (not just trusting CI green)

  • Compiled squad-retro.md myself with gh aw compile --strict (same technique CI's gh-aw-compile job uses). It compiles cleanly to a valid squad-retro.lock.yml with no warnings once run with repo remote context.
  • Cron strings: the unresolved review thread from copilot-pull-request-reviewer[bot] claims the schedule strings are invalid GitHub Actions cron and will fail to trigger. This is a false positive - gh-aw's documented "friendly schedule" syntax (the exact string used in gh-aw's own schedule-syntax docs) resolves these at compile time to valid 5-field cron. My local compile confirms it: emitted "26 2 * * 1" and "15 */6 * * *" with "Friendly format" comments. No fix needed.
  • Permissions: top-level permissions: {} with per-job scoping (agent job: read + copilot-requests: write, no issue/PR write; upsert_retro_state job: issues: write only, no PR write). This is the correct least-privilege split and matches the pattern used by other framework-generated jobs already in dev (compared against the compiled squad-review.lock.yml).
  • Bounded outputs: create-issue max 6, add-comment max 8, add-labels max 18, all with require-temporary-id/allowed label lists - consistent with the "Bounded actions, at most five issues" prose plus one for initialize_state.
  • No infinite-loop surface: squad-retro.md declares no dispatch-workflow safe output - it is a terminal receiver. Only squad-review (max 1, REQUEST_CHANGES only) and squad-implement-worker (max 3, persistent-failure only) may wake it, and both delegate the actual eligibility decision to the deterministic gate rather than deciding themselves.
  • Dedup/cooldown/pending recovery: evaluateRetro() in squad-retro-evidence.mjs fails closed on incomplete pagination or log truncation, preserves truncation_preserved_fingerprints as pending rather than resolving on missing evidence, requires an Action-Key match before opening a new action issue, and gates the durable state comment behind trusted-origin checks (bot author, open, correct label) before upsert. test/gh-aw-retro-workflow.test.ts has 46 targeted cases covering exactly these paths (threshold, cooldown expiry, legacy in-flight recovery, truncation fail-closed, low-confidence exclusion).
  • Router/authorization: /squad retro was correctly added to workflows/squad.md's authorization-required mode list (write/maintain/admin gate), not left as an open command.
  • Checks: all 18 applicable status checks pass against the current head SHA 4633a87 (gh-aw strict compile, security review, architectural review, tests, policy gates, changeset drift, etc.). mergeStateStatus is BEHIND but MERGEABLE - the 5 commits ahead on dev are unrelated dependency bumps.

Non-blocking notes

  • One open (unresolved) review thread from the Copilot reviewer bot re: cron syntax - recommend replying with the friendly-schedule compile evidence above and resolving it, since it is not accurate for this codebase's pinned gh-aw compiler.
  • Branch is BEHIND dev by 5 commits (dependency bumps only); update-branch before merge is routine, not a blocker.

No blocking findings. Approving.

bradygaster and others added 3 commits September 8, 2026 08:12
Closes github#2005

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Closes github#2005

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@tamirdresher
tamirdresher merged commit ea554fb into github:dev Sep 8, 2026
18 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants